---
title: lint-staged
description: Execute o Ultracite automaticamente nos seus arquivos Git staged com o lint-staged
---

Ultracite integra-se perfeitamente com [lint-staged](https://github.com/okonet/lint-staged) para formatar e lintar seu código automaticamente antes de cada commit. Isso garante que apenas código limpo e corretamente formatado entre no seu repositório.

## O que é o lint-staged?

lint-staged é uma ferramenta que executa linters e formatadores nos arquivos Git staged. É particularmente útil porque:

- Processa apenas os arquivos que estão realmente sendo comitados
- Evita que código mal formatado entre no seu repositório
- Executa rapidamente já que verifica apenas os arquivos alterados
- Integra-se perfeitamente com hooks do Git

## Como o Ultracite usa o lint-staged

Quando você executa `npx ultracite init`, se selecionar a opção lint-staged, o Ultracite automaticamente:

1. **Instala o lint-staged** como uma dependência de desenvolvimento
2. **Cria ou atualiza** sua configuração do lint-staged
3. **Configura o formatador** para rodar nos tipos de arquivo relevantes

A configuração padrão executa `npx ultracite fix` nesses tipos de arquivo:
- Arquivos JavaScript/TypeScript (`.js`, `.jsx`, `.ts`, `.tsx`)
- Arquivos JSON (`.json`, `.jsonc`)
- Arquivos CSS (`.css`, `.scss`)
- Arquivos Markdown (`.md`, `.mdx`)

## Formatos de Configuração Suportados

A integração do Ultracite com o lint-staged suporta todos os formatos de configuração padrão do lint-staged:

### package.json

```json title="package.json"
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx,json,jsonc,css,scss,md,mdx}": ["npx ultracite fix"]
  }
}
```

### .lintstagedrc.json

```json title=".lintstagedrc.json"
{
  "*.{js,jsx,ts,tsx,json,jsonc,css,scss,md,mdx}": ["npx ultracite fix"]
}
```

### .lintstagedrc.js (CommonJS)

```javascript title=".lintstagedrc.js"
module.exports = {
  "*.{js,jsx,ts,tsx,json,jsonc,css,scss,md,mdx}": ["npx ultracite fix"]
};
```

### .lintstagedrc.mjs (ES Modules)

```javascript title=".lintstagedrc.mjs"
export default {
  "*.{js,jsx,ts,tsx,json,jsonc,css,scss,md,mdx}": ["npx ultracite fix"]
};
```

### .lintstagedrc.yaml

```yaml title=".lintstagedrc.yaml"
"*.{js,jsx,ts,tsx,json,jsonc,css,scss,md,mdx}":
  - 'npx ultracite fix'
```

## Mesclagem Inteligente de Configuração

Se você já tem uma configuração do lint-staged, o Ultracite irá:

- **Detectar** o formato da sua configuração existente
- **Mesclar** as regras do Ultracite com suas regras existentes
- **Preservar** suas configurações personalizadas
- **Atualizar** o arquivo no local

Isso significa que você pode executar com segurança `npx ultracite init` mesmo se já tiver o lint-staged configurado.

## Como Funciona

1. **Hook pré-commit**: o lint-staged roda antes de cada commit via Husky
2. **Detecção de arquivos**: apenas os arquivos staged que correspondem aos padrões são processados
3. **Comando de formatação**: `npx ultracite fix` é executado em cada arquivo correspondente
4. **Auto-correção**: o Biome corrige automaticamente problemas quando possível
5. **Re-staging**: os arquivos corrigidos são automaticamente re-stageados para o commit

## Configuração Manual

Se precisar customizar sua configuração do lint-staged, você pode modificar a configuração após a inicialização:

```json title="package.json"
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["npx ultracite fix", "npm run test:unit"],
    "*.{json,jsonc}": ["npx ultracite fix"],
    "*.{css,scss}": ["npx ultracite fix", "npm run test:styles"],
    "*.{md,mdx}": ["npx ultracite fix"]
  }
}
```

## Integração com Comandos

A integração com o lint-staged funciona com a estrutura de comandos do Ultracite:

- **`npx ultracite fix`**: Executa o Biome com correção automática (usado pelo lint-staged)
- **`npx ultracite check`**: Executa o Biome sem correção automática (para CI/verificações manuais)

## Solução de Problemas

### Configuração não encontrada
Se você vir erros sobre configuração do lint-staged ausente:

```bash
npx ultracite init  # Re-execute a inicialização
```

### Problemas ESM/CommonJS
O Ultracite detecta automaticamente o tipo do seu projeto e cria o formato de configuração apropriado:

- **Projetos ESM** (com `"type": "module"` no package.json) recebem configurações `.mjs`
- **Projetos CommonJS** recebem configurações `.cjs`
- **Fallback**: Cria `.lintstagedrc.json` se a detecção de módulo falhar

### Conflitos com Configuração Existente
Se você tiver configurações existentes complexas, talvez seja necessário mesclar manualmente:

1. Faça backup da sua configuração existente do lint-staged
2. Execute `npx ultracite init`
3. Mescle manualmente quaisquer regras personalizadas que precise preservar

## Melhores Práticas

1. **Mantenha rápido**: Execute apenas as verificações essenciais no lint-staged
2. **Use padrões específicos**: Mire apenas nos arquivos que precisam de processamento
3. **Combine com CI**: Use o lint-staged para verificações rápidas locais e linting completo no CI
4. **Teste sua configuração**: Faça um commit de teste para garantir que tudo funciona

## Relacionados

- [Integração com Husky](/integration/husky) - Configuração de hooks do Git
- [Configuração](/configuration) - Opções de configuração do Biome
- [Configuração](/setup) - Configuração inicial do projeto